<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<head>
<!-- Copyright 1997 The Open Group, All Rights Reserved -->
<title>sigaction</title>
</head><body bgcolor=white>
<center>
<font size=2>
The Single UNIX &reg; Specification, Version 2<br>
Copyright &copy; 1997 The Open Group

</font></center><hr size=2 noshade>
<h4><a name = "tag_000_008_579">&nbsp;</a>NAME</h4><blockquote>
sigaction - examine and change signal action
</blockquote><h4><a name = "tag_000_008_580">&nbsp;</a>SYNOPSIS</h4><blockquote>
<pre><code>

#include &lt;<a href="signal.h.html">signal.h</a>&gt;

int sigaction(int <i>sig</i>, const struct sigaction *<i>act</i>,
    struct sigaction *<i>oact</i>);
</code>
</pre>
</blockquote><h4><a name = "tag_000_008_581">&nbsp;</a>DESCRIPTION</h4><blockquote>
The
<i>sigaction()</i>
function allows the calling process to examine and/or specify the
action to be associated with a specific signal.
The argument
<i>sig</i>
specifies the signal; acceptable values are defined in
<i><a href="signal.h.html">&lt;signal.h&gt;</a></i>.
<p>
The structure
<b>sigaction</b>,
used to describe an action to be taken, is defined in the header
<i><a href="signal.h.html">&lt;signal.h&gt;</a></i>
to include at least the following members:
<p><table  bordercolor=#000000 border=1 align=center><tr valign=top><th align=center><b>Member Type</b>
<th align=center><b>Member Name</b>
<th align=center><b>Description</b>
<tr valign=top><td align=left>void(*) (int)
<td align=left>sa_handler
<td align=left>SIG_DFL, SIG_IGN or pointer to a function.
<tr valign=top><td align=left>sigset_t
<td align=left>sa_mask
<td align=left> Additional set of signals to be blocked during execution of signal-catching function. 
<tr valign=top><td align=left>int
<td align=left>sa_flags
<td align=left>Special flags to affect behaviour of signal.
<tr valign=top><td align=left>void(*) (int,  siginfo_t *, void *)
<td align=left>sa_sigaction
<td align=left>Signal-catching function.
</table>
<p>
If the argument
<i>act</i>
is not a null pointer, it points to a structure specifying the action to be
associated with the specified signal.
If the argument
<i>oact</i>
is not a null pointer, the action previously associated with the signal is
stored in the location pointed to by the argument
<i>oact</i>.
If the argument
<i>act</i>
is a null pointer, signal handling is unchanged; thus, the call can be used
to enquire about the current handling of a given signal.
The
<i>sa_handler</i>
field of the
<b>sigaction</b>
structure identifies the action to be associated with the
specified signal.
If the
<i>sa_handler</i>
field specifies a signal-catching function, the
<i>sa_mask</i>
field identifies a set of signals that will be added to the
process' signal mask before the signal-catching function is
invoked.
The SIGKILL and SIGSTOP signals will not be added to the signal
mask using this mechanism; this restriction will be enforced by
the system without causing an error to be indicated.
<p>
If the SA_SIGINFO flag (see below) is cleared in the
<i>sa_flags</i>
field of the
<b>sigaction</b>
structure, the
<i>sa_handler</i>
field identifies the action to be associated with the specified signal.
If the SA_SIGINFO flag is set in the
<i>sa_flags</i>
field, the
<i>sa_sigaction</i>
field specifies a signal-catching function.
If the SA_SIGINFO bit is cleared and the
<i>sa_handler</i>
field specifies a signal-catching function, or if the
SA_SIGINFO bit is set, the
<i>sa_mask</i>
field identifies a set of signals
that will be added to the signal mask of the thread
before the signal-catching function is invoked.
<p>
The
<i>sa_flags</i>
field can be used to modify the behaviour of the specified
signal.
<p>
The following flags, defined in the header
<i><a href="signal.h.html">&lt;signal.h&gt;</a></i>,
can be set in
<i>sa_flags</i>:
<dl compact>

<dt>SA_NOCLDSTOP<dd>
Do not generate SIGCHLD when children stop.

<dt>ot generate SIGCHLD when children stop.<dd>
<dt>SA_ONSTACK<dd>
If set and an alternate signal stack has been declared with
<i><a href="sigaltstack.html">sigaltstack()</a></i>
or
<i><a href="sigstack.html">sigstack()</a></i>,
the signal will be delivered to the calling process on that stack.  Otherwise,
the signal will be delivered on the current stack.

<dt>SA_RESETHAND<dd>
If set, the disposition of the signal will be reset to SIG_DFL and the
SA_SIGINFO flag will be cleared on entry to the
signal handler.
<dl><dt><b>Note:</b>
<dd>SIGILL and SIGTRAP cannot be automatically reset
when delivered; the system silently enforces this restriction.
</dl>
Otherwise, the disposition of the signal will not be modified on entry
to the signal handler.
<p>
In addition, if this flag is set,
<i>sigaction()</i>
behaves as if the SA_NODEFER flag were also set.
<p>
<dt>SA_RESTART<dd>
This flag affects the behaviour of interruptible functions; that is,
those specified to fail with
<i>errno</i>
set to [EINTR].
If set, and a function specified as interruptible is interrupted by this
signal, the function will restart and will not fail with [EINTR] unless
otherwise specified.  If the flag is not set,
interruptible functions interrupted by this signal will fail with
<i>errno</i>
set to [EINTR].
<p>
<dt>SA_SIGINFO<dd>
If cleared and the signal is caught, the signal-catching function
will be entered as:
<pre>
<code>
void func(int <i>signo</i>);
</code>
</pre>
where <i>signo</i> is the only argument to the signal catching function.  In
this case the <b>sa_handler</b> member must be used to describe the signal
catching function and the application must not modify the <b>sa_sigaction</b>
member.
<p>
If SA_SIGINFO is set and the signal is caught, the signal-catching function
will be entered as:
<pre>
<code>
void func(int <i>signo</i>, siginfo_t *<i>info</i>, void *<i>context</i>);
</code>
</pre>
where two additional arguments are passed to the signal catching function.
The second argument will point to an object of type
<b>siginfo_t</b>
explaining the reason why the signal was generated;
the third argument can be cast to a pointer to an object of type
<b>ucontext_t</b>
to refer to the receiving process' context that was interrupted when
the signal was delivered.
In this case the <b>sa_sigaction</b> member must be used to
describe the signal catching function and the application must not modify the
<b>sa_handler</b> member.
<p>
The <b>si_signo</b> member contains the system-generated signal number.
<p>
The <b>si_errno</b> member may contain implementation-dependent additional
error information; if non-zero, it contains an error number identifying the
condition that caused the signal to be generated.
<p>
The <b>si_code</b> member contains a code identifying the cause of the signal.  If the
value of <b>si_code</b> is less than or equal to 0, then the signal was
generated by a process and <b>si_pid</b> and <b>si_uid</b> respectively indicate
the process ID and the real user ID of the sender.  
The 
<i><a href="signal.h.html">&lt;signal.h&gt;</a></i>
header description contains information about the signal
specific contents of the elements of the 
<b>siginfo_t</b>
type.
<p>
<dt>SA_NOCLDWAIT<dd>
If set, and <i>sig</i> equals SIGCHLD,
child processes of the calling processes will not be transformed into zombie
processes
when they terminate.  If the calling process subsequently waits for its
children, and the process has no unwaited for children that were transformed
into zombie processes, it will block until all of its children terminate, and
<i><a href="wait.html">wait()</a></i>,
<i><a href="wait3.html">wait3()</a></i>,
<i><a href="waitid.html">waitid()</a></i>
and
<i><a href="waitpid.html">waitpid()</a></i>
will fail and set
<i>errno</i>
to [ECHILD].
Otherwise, terminating child processes will be transformed into zombie
processes, unless SIGCHLD is set to SIG_IGN.
<p>
<dt>SA_NODEFER<dd>
If set and <i>sig</i> is caught,
<i>sig</i> will not be added to the process' signal mask on entry to the
signal handler unless it is included in <b>sa_mask</b>.  Otherwise, <i>sig</i>
will always be added to the process' signal mask on entry to the signal
handler.
<p>
</dl>
<p>
If
<i>sig</i>
is SIGCHLD and the SA_NOCLDSTOP flag is not set in
<i>sa_flags</i>,
and the implementation supports the SIGCHLD signal, then a
SIGCHLD signal will be generated for the calling process whenever
any of its child processes stop.
If
<i>sig</i>
is SIGCHLD and the SA_NOCLDSTOP flag is set in
<i>sa_flags</i>,
then the implementation will not generate a SIGCHLD signal in
this way.
<p>
When a signal is caught by a signal-catching function installed by
<i>sigaction()</i>,
a new signal mask is calculated and installed for the
duration of the signal-catching function (or until a call to
either
<i><a href="sigprocmask.html">sigprocmask()</a></i>
or
<i><a href="sigsuspend.html">sigsuspend()</a></i>
is made).
This mask is formed by taking the union of the current signal
mask and the value of the
<i>sa_mask</i>
for the signal being delivered
&nbsp;unless SA_NODEFER or SA_RESETHAND is set,
and then including the signal being delivered.
If and when the user's signal handler returns normally, the
original signal mask is restored.
<p>
Once an action is installed for a specific signal, it remains
installed until another action is explicitly requested (by
another call to
<i>sigaction()</i>),
until the SA_RESETHAND flag causes resetting of the handler,
or until one of the
<i>exec</i>
functions is called.
<p>
If the previous action for
<i>sig</i>
had been established by
<i><a href="signal.html">signal()</a></i>,
the values of the fields returned in the structure pointed to by
<i>oact</i>
are unspecified, and in particular
<i>oact-&gt;sa_handler</i>
is not necessarily the same value passed to
<i><a href="signal.html">signal()</a></i>.
However, if a pointer to the same structure or a copy thereof is
passed to a subsequent call to
<i>sigaction()</i>
via the
<i>act</i>
argument, handling of the signal will be as if the original call to
<i><a href="signal.html">signal()</a></i>
were repeated.
<p>
If
<i>sigaction()</i>
fails, no new signal handler is installed.
<p>
It is unspecified whether an attempt to set the action for a signal
that cannot be caught or ignored to SIG_DFL is ignored or causes an
error to be returned with
<i>errno</i>
set to [EINVAL].
<p>
If SA_SIGINFO is not set in
<i>sa_flags</i>,
then the disposition of subsequent occurrences of
<i>sig</i>
when it is already pending is implementation-dependent;
the signal-catching function will be invoked with a single argument.
If the implementation supports the Realtime Signals Extension option,
and if SA_SIGINFO is set in
<i>sa_flags,</i>
then subsequent occurrences of
<i>sig</i>
generated by
<i><a href="sigqueue.html">sigqueue()</a></i>
or as a result of any signal-generating function
that supports the specification of an application-defined value (when
<i>sig</i>
is already pending) will be queued in FIFO order until delivered
or accepted;
the signal-catching function will be invoked with three arguments.
The application specified value is passed
to the signal-catching function as the
<i>si_value</i>
member of the
<b>siginfo_t</b>
structure.
<h5><a name = "tag_000_008_581_001">&nbsp;</a>Signal Generation and Delivery</h5>
<xref type="5" name="siggendel"></xref>
<p>
A signal is said to be
<i>generated</i>
for (or sent to) a process or thread 
when the event that causes the signal
first occurs.
Examples of such events include detection of hardware faults,
timer expiration,
signals generated via the
<b>sigevent</b>
structure
and terminal activity, as well as invocations of
<i><a href="kill.html">kill()</a></i>
and
<i><a href="sigqueue.html">sigqueue()</a></i>
functions.
In some circumstances, the same event generates signals for
multiple processes.
<p>
At the time of generation, a determination is made whether
the signal has been generated for the process
or for a specific thread within the process.
Signals which are generated by some action attributable to a
particular thread, such as a hardware fault,
are generated for the thread that caused the signal to be
generated.
Signals that are generated in association
with a process ID or process group ID
or an asynchronous event such as terminal activity
are generated for the process.
<p>
Each process has an action to be taken in response to each signal
defined by the system (see
<xref href=sigact><a href="#tag_000_008_581_002">
Signal Actions
</a></xref>).
A signal is said to be
<i>delivered</i>
to a process when the appropriate action for the process and
signal is taken.
A signal is said to be
<i>accepted</i>
by a process when the signal is selected and returned by one of the
<i><a href="sigwait.html">sigwait()</a></i>
functions.
<p>
During the time between the generation of a signal and its
delivery or acceptance, the signal is said to be
<i>pending</i>.
Ordinarily, this interval cannot be detected by an application.
However, a signal can be
<i>blocked</i>
from delivery to a thread
If the action associated with a blocked signal is anything other
than to ignore the signal, and if that signal is generated for
the thread the signal will remain pending until it is unblocked,
it is accepted when it is selected and returned by a call to the
<i><a href="sigwait.html">sigwait()</a></i>
function, or the action associated with it is set to ignore the signal.
Signals generated for the process will be delivered to
exactly one of those threads
within the process which is in a call to a
<i><a href="sigwait.html">sigwait()</a></i>
function selecting that signal or has not blocked delivery of the
signal.
If there are no threads in a call to a
<i><a href="sigwait.html">sigwait()</a></i>
function selecting that signal, and
if all threads within the process block delivery of the signal,
the signal will remain pending on the process until a thread calls a
<i><a href="sigwait.html">sigwait()</a></i>
function selecting that signal,
a thread unblocks delivery of the signal,
or the action associated with the signal is set to ignore the signal.
If the action associated with a blocked signal is to ignore the
signal and if that signal is generated for the process, it is
unspecified whether the signal is discarded immediately upon
generation or remains pending.
<p>
Each thread 
has a
<i>signal mask</i>
that defines the set of signals currently blocked from delivery
to it.
The signal mask for a thread 
is initialised from that of its
parent
or creating thread, or from the corresponding thread in the parent
process if the thread was created as the result of a call to
<i><a href="fork.html">fork()</a></i>.
The
<i>sigaction()</i>,
<i><a href="sigprocmask.html">sigprocmask()</a></i>
and
<i><a href="sigsuspend.html">sigsuspend()</a></i>
functions control the manipulation of the signal mask.
<p>
The determination of which action is taken in response to a
signal is made at the time the signal is delivered, allowing for
any changes since the time of generation.
This determination is independent of the means by which the
signal was originally generated.
If a subsequent occurrence of a pending signal is generated, it
is implementation-dependent as to whether the signal is delivered
or accepted more than once in circumstances
other than those
in which queueing is required under the Realtime Signals Extension option.
The order in which multiple, simultaneously pending signals
outside the range SIGRTMIN to SIGRTMAX are delivered to or accepted by
a process is unspecified.
<p>
When any stop signal (SIGSTOP, SIGTSTP, SIGTTIN, SIGTTOU) is
generated for a process, any pending SIGCONT signals for that
process will be discarded.
Conversely, when SIGCONT is generated for a process, all pending
stop signals for that process will be discarded.
When SIGCONT is generated for a process that is stopped, the
process will be continued, even if the SIGCONT signal is blocked
or ignored.
If SIGCONT is blocked and not ignored, it will remain pending
until it is either unblocked or a stop signal is generated for
the process.
<p>
An implementation will document any condition not specified by
this document under which the implementation generates signals.
<p>
Some signal-generating functions, such as
high-resolution timer expiration,
asynchronous I/O completion, interprocess message arrival, and the
<i><a href="sigqueue.html">sigqueue()</a></i>
function,
support the specification of an application-defined value,
either explicitly as a parameter to the function or in a
<b>sigevent</b> structure parameter.
The <b>sigevent</b> structure is defined in
<i><a href="signal.h.html">&lt;signal.h&gt;</a></i>
and contains at least the following members:
<p><table  bordercolor=#000000 border=1 align=center><tr valign=top><th align=center><b>Member Type</b>
<th align=center><b>Member Name</b>
<th align=center><b>Description</b>
<tr valign=top><td align=left>int
<td align=left>sigev_notify
<td align=left>Notification type
<tr valign=top><td align=left>int
<td align=left>sigev_signo
<td align=left>Signal number
<tr valign=top><td align=left>union sigval
<td align=left>sigev_value
<td align=left>Signal value
<tr valign=top><td align=left>void(*)(unsigned sigval)
<td align=left>sigev_notify_function
<td align=left>Notification function
<tr valign=top><td align=left>(pthread_attr_t*)
<td align=left>sigev_notify_attributes
<td align=left>Notification attributes
</table>
<p>
The 
<i>sigev_notify</i>
member specifies the notification mechanism to use
when an asynchronous event occurs.
This document defines the following values for the
<i>sigev_notify</i>
member:
<dl compact>

<dt>SIGEV_NONE<dd>
No asynchronous notification will be delivered
when the event of interest occurs.

<dt>SIGEV_SIGNAL<dd>
The signal specified in
<i>sigev_signo</i>
will be generated for the process when the event of interest occurs.
If the implementation supports the Realtime Signals Extension option
and if the SA_SIGINFO flag is set for that signal number, then the signal
will be queued to the process and the value specified in
<i>sigev_value</i>
will be the
<i>si_value</i>
component of the generated signal.
If SA_SIGINFO is not set for that signal number, it is unspecified whether
the signal is queued and what value, if any, is sent.

<dt>SIGEV_THREAD<dd>
A notification function will be called to perform notification.

</dl>
<p>
An implementation may define additional notification mechanisms.
<p>
The
<i>sigev_signo</i>
member specifies the signal to be generated.
The
<i>sigev_value</i>
member is the application-defined value
to be passed to the signal-catching function
at the time of the signal delivery
or to be returned at signal acceptance as the
<i>si_value</i>
member of the
<b>siginfo_t</b>
structure.
<p>
The
<b>sigval</b>
union is defined in
<i><a href="signal.h.html">&lt;signal.h&gt;</a></i>
and contains at least the following members:
<p><table  bordercolor=#000000 border=1 align=center><tr valign=top><th align=center><b>Member Type</b>
<th align=center><b>Member Name</b>
<th align=center><b>Description</b>
<tr valign=top><td align=left>int
<td align=left>sival_int
<td align=left>Integer signal value
<tr valign=top><td align=left>void*
<td align=left>sival_ptr
<td align=left>Pointer signal value
</table>
<p>
The
<i>sival_int</i>
member is used when the application-defined value is of type
<b>int</b>;
the
<i>sival_ptr</i>
member is used when the application-defined value is a pointer.
<p>
If the Realtime Signals Extension option is supported:
<dl compact><dt> <dd>
When a signal is generated by the
<i><a href="sigqueue.html">sigqueue()</a></i>
function
or any signal-generating function that supports the specification
of an application-defined value,
the signal will be marked pending and, if the SA_SIGINFO
flag is set for that signal, the signal will be queued to the process
along with the application-specified signal value.
Multiple occurrences of signals so generated are queued in FIFO
order.
It is unspecified whether signals so generated are queued when the
SA_SIGINFO flag is not set for that signal.
<p>
Signals generated by the
<i><a href="kill.html">kill()</a></i>
function or other events that cause signals to occur,
such as detection of hardware faults,
<i><a href="alarm.html">alarm()</a></i>
timer expiration, or terminal activity,
and for which the implementation does not support queuing,
have no effect on signals already queued for the same signal
number.
</dl>
<dl compact><dt> <dd>
When multiple unblocked signals, all in the range
SIGRTMIN to SIGRTMAX, are pending,
the behaviour will be as if
the implementation delivers the pending unblocked signal
with the lowest signal number within that range.
No other ordering of signal delivery is specified.
<p>
If, when a pending signal is delivered,
there are additional signals queued to that signal number,
the signal remains pending.
Otherwise, the pending indication is reset.
</dl>
<p>
Multi-threaded programs can use an alternate event notification
mechanism:
<dl compact><dt> <dd>
When a notification is processed, and the
<i>sigev_notify</i>
member of the
<b>sigevent</b>
structure has the value SIGEV_THREAD, the function
<i>sigev_notify_function</i>
is called with parameter
<i>sigev_value</i>.
<p>
The function will be executed in an environment
as if it were the
<i>start_routine</i>
for a newly created thread with thread attributes specified by
<i>sigev_notify_attributes</i>.
If
<i>sigev_notify_attributes</i>
is NULL, the behaviour will as if the thread were created with the
<i>detachstate</i>
attribute set to PTHREAD_CREATE_DETACHED.
Supplying an attributes structure with a
<i>detachstate</i>
attribute of PTHREAD_CREATE_JOINABLE
results in undefined behaviour.
The signal mask of this thread is implementation-dependent.
</dl>
<h5><a name = "tag_000_008_581_002">&nbsp;</a>Signal Actions</h5>
<xref type="5" name="sigact"></xref>
There are three types of action that can be associated with a
signal: SIG_DFL, SIG_IGN or a
<i>pointer to a function</i>.
Initially, all signals will be set to SIG_DFL or SIG_IGN prior to
entry of the
<i>main()</i>
routine (see the
<i>exec</i>
functions).
The actions prescribed by these values are as follows:
<dl compact>

<dt>SIG_DFL - signal-specific default action<dd><ul>

<li>
The default actions for the signals defined in this specification are
specified under
<i><a href="signal.h.html">&lt;signal.h&gt;</a></i>.
If the Realtime Signals Extension option is supported,
the default actions for the realtime signals in the range SIGRTMIN to
SIGRTMAX are to terminate the process abnormally.

<li>
If the default action is to stop the process, the execution of
that process is temporarily suspended.
When a process stops, a SIGCHLD signal will be generated for its
parent process, unless the parent process has set the
SA_NOCLDSTOP flag.
While a process is stopped, any additional signals that are sent
to the process will not be delivered until the process is
continued, except SIGKILL which always terminates the receiving
process.
A process that is a member of an orphaned process group will not
be allowed to stop in response to the SIGTSTP, SIGTTIN or
SIGTTOU signals.
In cases where delivery of one of these signals would stop such a
process, the signal will be discarded.

<li>
Setting a signal action to SIG_DFL for a signal that is pending,
and whose default action is to ignore the signal (for example, SIGCHLD),
will cause the pending signal to be discarded, whether or not it
is blocked.
If the Realtime Signals Extension option is supported,
any queued values pending will be discarded and the resources used to
queue them will be released and made available to queue other signals.

</ul>

<dt>SIG_IGN - ignore signal<dd>
<ul>

<li>
Delivery of the signal will have no effect on the process.
The behaviour of a process is undefined after it ignores a
SIGFPE, SIGILL, SIGSEGV 
or SIGBUS
signal that was not generated by
<i><a href="kill.html">kill()</a></i>,
<i><a href="sigqueue.html">sigqueue()</a></i>
or
<i><a href="raise.html">raise()</a></i>.

<li>
The system will not allow the action for the signals SIGKILL or
SIGSTOP to be set to SIG_IGN.

<li>
Setting a signal action to SIG_IGN for a signal that is pending
will cause the pending signal to be discarded, whether or not it
is blocked.

<li>
If a process sets the action for the SIGCHLD signal to SIG_IGN,
the behaviour is unspecified,
except as specified below.

If the action for the SIGCHLD signal is set to SIG_IGN,
child processes of the calling processes will not be transformed into zombie
processes
when they terminate.  If the calling process subsequently waits for its
children, and the process has no unwaited for children that were transformed
into zombie processes, it will block until all of its children terminate, and
<i><a href="wait.html">wait()</a></i>,
<i><a href="wait3.html">wait3()</a></i>,
<i><a href="waitid.html">waitid()</a></i>
and
<i><a href="waitpid.html">waitpid()</a></i>
will fail and set
<i>errno</i>
to [ECHILD].

If the Realtime Signals Extension option is supported,
any queued values pending will be discarded and the resources used to
queue them will be released and made available to queue other signals.

</ul>

<dt><i>pointer to a function</i> - catch signal<dd><ul>

<li>
On delivery of the signal, the receiving process is to execute
the signal-catching function at the specified address.
After returning from the signal-catching function, the receiving
process will resume execution at the point at which it was
interrupted.

If the SA_SIGINFO
flag for the signal is cleared, the signal-catching function
will be entered as a C language function call as follows:
<pre>
<code>
void <i>func</i>(int <i>signo</i>);
</code>
</pre>
If the SA_SIGINFO flag for the signal is set, the signal-catching 
function will be entered as a C language function call as follows:
<pre>
<code>
void <i>func</i>(int <i>signo</i>, siginfo_t *<i>info</i>, void *<i>context</i>);
</code>
</pre>
where
<i>func</i>
is the specified signal-catching function,
<i>signo</i>
is the signal number of the signal being delivered, and
<i>info</i>
is a pointer to a
<b>siginfo_t</b>
structure defined in
<i><a href="signal.h.html">&lt;signal.h&gt;</a></i>
containing at least the following member(s):
<table  bordercolor=#000000 border=1 align=center><tr valign=top><th align=center><b>Member Type</b>
<th align=center><b>Member Name</b>
<th align=center><b>Description</b>
<tr valign=top><td align=left>int
<td align=left>si_signo
<td align=left>Signal number
<tr valign=top><td align=left>int
<td align=left>si_code
<td align=left>Cause of the signal
<tr valign=top><td align=left>union sigval
<td align=left>si_value
<td align=left>Signal value
</table>

The
<i>si_signo</i>
member contains the signal number.
This is the same as the
<i>signo</i>
parameter.
The
<i>si_code</i>
member contains a code identifying the cause of the signal.
The following values are defined for
<i>si_code</i>:
<dl compact>

<dt>SI_USER<dd>
The signal was sent by the
<i><a href="kill.html">kill()</a></i>
function.
The implementation may set
<i>si_code</i>
to SI_USER if the signal was sent by the
<i><a href="raise.html">raise()</a></i>
or
<i><a href="abort.html">abort()</a></i>
functions
or any similar functions provided as implementation extensions.

<dt>SI_QUEUE<dd>
The signal was sent by the
<i><a href="sigqueue.html">sigqueue()</a></i>
function.

<dt>SI_TIMER<dd>
The signal was generated by the expiration of a timer set by
<i><a href="timer_settime.html">timer_settime()</a></i>.

<dt>SI_ASYNCIO<dd>
The signal was generated by the completion of an
asynchronous I/O request.

<dt>SI_MESGQ<dd>
The signal was generated by the arrival of a message on an
empty message queue.

</dl>
<p>
If the signal was not generated
by one of the functions or events listed above, the
<i>si_code</i>
will be set to an implementation-dependent value
that is not equal to any of the values defined above.
<p>
If the Realtime Signals Extension is supported,
and
<i>si_code</i>
is one of SI_QUEUE, SI_TIMER, SI_ASYNCIO, or SI_MESGQ, then
<i>si_value</i>
contains the application-specified signal value.
Otherwise, the contents of
<i>si_value</i>
are undefined.
<p>
<li>
The behaviour of a process is undefined after it returns normally
from a signal-catching function for a
&nbsp;SIGBUS,
SIGFPE, SIGILL or SIGSEGV signal that was not generated by
<i><a href="kill.html">kill()</a></i>,
<i><a href="sigqueue.html">sigqueue()</a></i>
or
<i><a href="raise.html">raise()</a></i>.
<p>
<li>
The system will not allow a process to catch the signals SIGKILL
and SIGSTOP.
<p>
<li>
If a process establishes a signal-catching function for the
SIGCHLD signal while it has a terminated child process for which
it has not waited, it is unspecified whether a SIGCHLD signal is
generated to indicate that child process.
<p>
<li>
When signal-catching functions are invoked asynchronously with process
execution, the behaviour of some of the functions defined by
this document is unspecified if they are called from a signal-catching
function.
<p>
The following table defines a set of interfaces that are either
reentrant or not interruptible by signals and are async-signal safe.
Therefore applications may invoke them, without
restriction, from signal-catching functions:
<p>
</ul>
<p>
</dl>
<h5><a name = "tag_000_008_581_003">&nbsp;</a>Base Interfaces</h5>
<p>
_exit()
access()
alarm()
cfgetispeed()
cfgetospeed()
cfsetispeed()
cfsetospeed()
chdir()
chmod()
chown()
close()
creat()
dup()
dup2()
execle()
execve()
fcntl()
fork()
fpathconf()
fstat()
fsync()
getegid()
geteuid()
getgid()
getgroups()
getpgrp()
getpid()
getppid()
getuid()
kill()
link()
lseek()
mkdir()
mkfifo()
open()
pathconf()
pause()
pipe()
raise()
read()
rename()
rmdir()
setgid()
setpgid()
setsid()
setuid()
sigaction()
sigaddset()
sigdelset()
sigemptyset()
sigfillset   ()
sigismember()
signal()
sigpending()
sigprocmask()
sigsuspend()
sleep()
stat()
sysconf()
tcdrain()
tcflow()
tcflush()
tcgetattr()
tcgetpgrp()
tcsendbreak()
tcsetattr()
tcsetpgrp()
time()
times()
umask()
uname()
unlink()
utime()
wait()
waitpid()
write()
<p>
<h5><a name = "tag_000_008_581_004">&nbsp;</a>Realtime Interfaces</h5>
<p><table <tr valign=top><td align=left><i><i>aio_error</i>()</i>
<td align=left><i><i>clock_gettime</i>()</i>
<td align=left><i><i>sigpause</i>()</i>
<td align=left><i><i>timer_getoverrun</i>()</i>
<tr valign=top><td align=left><i><i>aio_return</i>()</i>
<td align=left><i><i>fdatasync</i>()</i>
<td align=left><i><i>sigqueue</i>()</i>
<td align=left><i><i>timer_gettime</i>()</i>
<tr valign=top><td align=left><i><i>aio_suspend</i>()</i>
<td align=left><i><i>sem_post</i>()</i>
<td align=left><i><i>sigset</i>()</i>
<td align=left><i><i>timer_settime</i>()  </i>
</table>
<p>
All functions not in the above table are considered to be unsafe
with respect to signals.
In the presence of signals, all functions defined by this specification
will behave as defined when called from or interrupted by a signal-catching
function, with a single exception: when a signal interrupts an unsafe
function and
the signal-catching function calls an unsafe function, the behaviour
is undefined.
<p>
</>
<p>
</>
<p>
When a signal is delivered to a thread,
if the action of that signal specifies termination, stop, or continue,
the entire process will be terminated, stopped, or continued,
respectively.
<h5><a name = "tag_000_008_581_005">&nbsp;</a>Signal Effects on Other Functions</h5>
Signals affect the behaviour of certain functions defined by this
specification if delivered to a process while it is executing such a
function.
If the action of the signal is to terminate the process, the
process will be terminated and the function will not return.
If the action of the signal is to stop the process, the process
will stop until continued or terminated.
Generation of a SIGCONT signal for the process causes the process
to be continued, and the original function will continue at the point
the process was stopped.
If the action of the signal is to invoke a signal-catching
function, the signal-catching function will be invoked; in this
case the original function is said to be
<i>interrupted</i>
by the signal.
If the signal-catching function executes a
<b>return</b>
statement,
the behaviour of the interrupted function will be as described
individually for that function.
Signals that are ignored will not affect the behaviour of any
function; signals that are blocked will not affect the behaviour
of any function until they are unblocked and then delivered,
except as specified for the
<i><a href="sigpending.html">sigpending()</a></i>
and the 
<i><a href="sigwait.html">sigwait()</a></i>
functions.
<p>
The result of the use of
<i>sigaction()</i>
and a
<i><a href="sigwait.html">sigwait()</a></i>
function concurrently within a process on the same signal is
unspecified.
</blockquote><h4><a name = "tag_000_008_582">&nbsp;</a>RETURN VALUE</h4><blockquote>
Upon successful completion,
<i>sigaction()</i>
returns 0.  Otherwise -1 is returned,
<i>errno</i>
is set to indicate the error and no new signal-catching function
will be installed.
</blockquote><h4><a name = "tag_000_008_583">&nbsp;</a>ERRORS</h4><blockquote>
The
<i>sigaction()</i>
function will fail if:
<dl compact>

<dt>[EINVAL]<dd>
The
<i>sig</i>
argument is not a valid signal number or an attempt is made to
catch a signal that cannot be caught or ignore a signal that
cannot be ignored.

</dl>
<p>
The
<i>sigaction()</i>
function may fail if:
<dl compact>

<dt>[EINVAL]<dd>
An attempt was made to set the action to SIG_DFL for a signal
that cannot be caught or ignored (or both).

</dl>
</blockquote><h4><a name = "tag_000_008_584">&nbsp;</a>EXAMPLES</h4><blockquote>
None.
</blockquote><h4><a name = "tag_000_008_585">&nbsp;</a>APPLICATION USAGE</h4><blockquote>
The
<i>sigaction()</i>
function supersedes the
<i><a href="signal.html">signal()</a></i>
interface, and should be used in preference.  In particular,
<i>sigaction()</i>
and
<i><a href="signal.html">signal()</a></i>
should not be used in the same process to control the same signal.
The behaviour of reentrant interfaces, as defined in the
description,
is as specified by this specification, regardless of invocation from a
signal-catching function.
This is the only intended meaning of the statement that reentrant
interfaces may be used in signal-catching functions without
restrictions.
Applications must still consider all effects of such functions on
such things as data structures, files and process state.
In particular, application writers need to consider the
restrictions on interactions when interrupting
<i><a href="sleep.html">sleep()</a></i>
and interactions among multiple handles for a file description.
The fact that any specific interface is listed as reentrant does
not necessarily mean that invocation of that interface from a
signal-catching function is recommended.
<p>
In order to prevent errors arising from interrupting
non-reentrant function calls, applications should protect calls
to these functions either by blocking the appropriate signals or
through the use of some programmatic semaphore (see
<i><a href="semget.html">semget()</a></i>,
<i><a href="sem_init.html">sem_init()</a></i>,
<i><a href="sem_open.html">sem_open()</a></i>,
and so on).
Note in particular that even the &quot;safe&quot; functions may modify
<i>errno</i>;
the signal-catching function, if not executing as an independent
thread, may want to save and restore its value.
Naturally, the same principles apply to the reentrancy of
application routines and asynchronous data access.
Note that
<i><a href="longjmp.html">longjmp()</a></i>
and
<i><a href="siglongjmp.html">siglongjmp()</a></i>
are not in the list of reentrant interfaces.
This is because the code executing after
<i><a href="longjmp.html">longjmp()</a></i>
and
<i><a href="siglongjmp.html">siglongjmp()</a></i>
can call any unsafe functions with the same danger as calling those
unsafe functions directly from the signal handler.
Applications that use
<i><a href="longjmp.html">longjmp()</a></i>
and
<i><a href="siglongjmp.html">siglongjmp()</a></i>
from within signal handlers require rigorous protection in order to be
portable.
Many of the other functions that are excluded from the list are
traditionally implemented using either
<i><a href="malloc.html">malloc()</a></i>
or
<i><a href="free.html">free()</a></i>
functions or the standard I/O library, both of which
traditionally use data structures in a non-reentrant manner.
Because any combination of different functions using a common
data structure can cause reentrancy problems, this document does not
define the behaviour when any unsafe
function is called in a signal handler that interrupts an unsafe function.
<p>
If the signal occurs other than as the result of calling
<i><a href="abort.html">abort()</a></i>,
<i><a href="kill.html">kill()</a></i>
or
<i><a href="raise.html">raise()</a></i>,
the behaviour is undefined if the signal handler calls
any function in the standard library other than one of the
functions listed in the table above
or refers to any object with static storage duration
other than by assigning a value to a static storage duration
variable of type
<b>volatile</b>
<b>sig_atomic_t</b>.
Furthermore, if such a call fails,
the value of
<i>errno</i>
is indeterminate.
<p>
Usually, the signal is executed on the stack that was in effect before the
signal was delivered.  An alternate stack may be specified to receive a subset
of the signals being caught.
<p>
When the signal handler returns, the receiving process will resume execution
at the point it was interrupted unless the signal handler makes other
arrangements.  If
<i><a href="longjmp.html">longjmp()</a></i>
or
<i><a href="_longjmp.html">_longjmp()</a></i>
is used to leave the signal handler, then the signal mask must be explicitly
restored by the process.
<p>
The ISO&nbsp;POSIX-1 standard defines the third argument of a signal handling function when
SA_SIGINFO is set as a <b>void&nbsp;*</b> instead of a <b>ucontext_t&nbsp;*</b>,
but without requiring type checking.  New applications should explicitly cast
the third argument of the signal handling function to <b>ucontext_t *</b>.
<p>
The BSD optional four argument signal handling function is not supported by
this specification.  The BSD declaration would be:
<pre>
<code>
void handler(int <i>sig</i>, int <i>code</i>, struct sigcontext *<i>scp</i>,
    char *<i>addr</i>);
</code>
</pre>
<p>
where <i>sig</i> is the signal number, <i>code</i> is additional information on
certain signals, <i>scp</i> is a pointer to the sigcontext structure, and
<i>addr</i> is additional address information.  Much the same information is
available in the objects pointed to by the second argument of the
signal handler specified when SA_SIGINFO is set.
</blockquote><h4><a name = "tag_000_008_586">&nbsp;</a>FUTURE DIRECTIONS</h4><blockquote>
The
<i><a href="fpathconf.html">fpathconf()</a></i>
function is marked as an extension in the list of safe functions
because it is not included in the corresponding list in the ISO&nbsp;POSIX-1 standard,
but it is expected to be added in a future revision of that
standard.
</blockquote><h4><a name = "tag_000_008_587">&nbsp;</a>SEE ALSO</h4><blockquote>
<i><a href="bsd_signal.html">bsd_signal()</a></i>,
<i><a href="kill.html">kill()</a></i>,
<i><a href="_longjmp.html">_longjmp()</a></i>,
<i><a href="longjmp.html">longjmp()</a></i>,
<i><a href="raise.html">raise()</a></i>,
<i><a href="semget.html">semget()</a></i>,
<i><a href="sem_init.html">sem_init()</a></i>,
<i><a href="sem_open.html">sem_open()</a></i>,
<i><a href="sigaddset.html">sigaddset()</a></i>,
<i><a href="sigaltstack.html">sigaltstack()</a></i>,
<i><a href="sigdelset.html">sigdelset()</a></i>,
<i><a href="sigemptyset.html">sigemptyset()</a></i>,
<i><a href="sigfillset.html">sigfillset()</a></i>,
<i><a href="sigismember.html">sigismember()</a></i>,
<i><a href="signal.html">signal()</a></i>,
<i><a href="sigprocmask.html">sigprocmask()</a></i>,
<i><a href="sigsuspend.html">sigsuspend()</a></i>,
<i><a href="wait.html">wait()</a></i>,
<i><a href="wait3.html">wait3()</a></i>,
<i><a href="waitid.html">waitid()</a></i>,
<i><a href="waitpid.html">waitpid()</a></i>,
<i><a href="signal.h.html">&lt;signal.h&gt;</a></i>,
<i><a href="ucontext.h.html">&lt;ucontext.h&gt;</a></i>.
<br>
</blockquote><h4>DERIVATION</h4><blockquote>
Derived from the POSIX.1-1988 standard.
</blockquote><hr size=2 noshade>
<center><font size=2>
UNIX &reg; is a registered Trademark of The Open Group.<br>
Copyright &copy; 1997 The Open Group
<br> [ <a href="../index.html">Main Index</a> | <a href="../xshix.html">XSH</a> | <a href="../xcuix.html">XCU</a> | <a href="../xbdix.html">XBD</a> | <a href="../cursesix.html">XCURSES</a> | <a href="../xnsix.html">XNS</a> ]

</font></center><hr size=2 noshade>
</body></html>

